subscribed.event_machine

An event machine structure slightly resembling finite automata.

  • EventMachine

    Declaration

    struct EventMachine(State_, T = void delegate()) if (is(typeof(State_.init)) && (State_.min != State_.max) && isCallable!T);

    A state machine with simplified transitions - a wrapper around a state collection. State-dependent transitions should be implemented using beforeEach/afterEach hooks. A transition can be canceled by returning false from the any beforeEach listeners. The machine has an initial state and a set of alternative states (loops are permitted). Any state can transition to any other state (the initial state is unreachable after transitioning away from it).

    Parameters

    State_

    An enum of available states.

    T

    The listener type this event contains. Default is void delegate().

    Examples

    An event machine stores it's state.

    1. enum State { stateA, stateB } alias Machine = EventMachine!State; Machine machine; assert(machine.state == State.stateA, "The machine is not initially in it's default state"); machine.go!(State.stateB)(); assert(machine.state == State.stateB, "The machine does not navigate to other states"); machine.go!(State.stateB)(); assert(machine.state == State.stateB, "The machine does not permit loops"); machine.go!(State.stateA)(); assert(machine.state == State.stateA, "The machine does not navigate to other states");

    Examples

    An event machine supports enums with negative values.

    1. enum State { stateA = -21, stateB = 3 } alias Machine = EventMachine!State; Machine machine; assert(machine.state == State.stateA, "The machine is not initially in it's default state"); machine.go!(State.stateB)(); assert(machine.state == State.stateB, "The machine does not navigate to other states");

    Examples

    beforeEach and afterEach run appropriately.

    1. enum State { stateA, stateB } alias Machine = EventMachine!(State, void delegate()); Machine machine; bool beforeEachRan, afterEachRan; machine.beforeEach ~= (oldState, newState) { assert(oldState == State.stateA, "The machine doesn't move from it's initial state"); assert(newState == State.stateB, "The machine doesn't move to a non-initial state"); beforeEachRan = true; return true; }; machine.afterEach ~= (oldState, newState) { afterEachRan = true; assert(oldState == State.stateA, "The machine doesn't move from it's initial state"); assert(newState == State.stateB, "The machine doesn't move to a non-initial state"); }; machine.go!(State.stateB)(); assert(beforeEachRan, "The beforeEach hook has been ran"); assert(afterEachRan, "The afterEach hook has been ran");

    Examples

    beforeEach can cancel subsequent events.

    1. enum State { stateA, stateB } alias Machine = EventMachine!(State, void delegate()); Machine machine; machine.beforeEach ~= (oldState, newState) { return false; }; machine.on!(State.stateA)(() { assert(false, "The machine moves to stateA despite the failing beforeEach check"); }); machine.go!(State.stateA)();

    • State

      Declaration

      alias State = State_;

      An alias to the State_ parameter.

    • EventType

      Declaration

      alias EventType = Event!T;

      The events' type.

    • beforeEach

      Declaration

      Event!(bool delegate(State, State)) beforeEach;

      The hook to be executed before any transition. If false is returned, no transition occurs.

    • afterEach

      Declaration

      Event!(void delegate(State, State)) afterEach;

      The hook to be executed after a successful transition.

    • state

      Declaration

      const State state();

      The active state.

    • on

      Declaration

      void on(State state)(EventType.ListenerType[] listeners...);

      A function for appending listeners to the state event. Can also be called using the alias on!#{stateName}, where the state name is a string.

      Parameters

      state

      The state whose event to subscribe to.

      EventType.ListenerType[] listeners

      The listeners to append.

      See Also

      subscribed.event.Event.append

    • off

      Declaration

      void off(State state)(EventType.ListenerType[] listeners...);

      A function for removing listeners from the state event.

      Parameters

      state

      The state whose event to remove from.

      EventType.ListenerType[] listeners

      The listeners to remove.

      See Also

      subscribed.event.Event.append

    • go

      Declaration

      void go(State state)(EventType.ParamTypes params);

      Calls all the registered listeners in order. Can also be called using the alias go!#{stateName}, where the state name is a string.

      Parameters

      state

      The state to transition to.

      EventType.ParamTypes params

      The param tuple to call the listener with.

      Return Value

      An array of results from the listeners. If EventType.ReturnType is void, then this function also returns void.

      See Also

      subscribed.event.Event.call